<html>
<head>
<title>How to build and run MORE?</title>
  <style type="text/css">
  h1 { font-size: 16pt; padding: 4pt; background-color: #AABBF0 }
  h2 { font-size: 14pt; font-style: italic; }
  body { font-size: 10pt; font-family: tahoma, sans; }
  pre { padding-left: 8pt; border: 1px dashed; background-color: #F0F0CC; }
  tt { font-weight: bold; }
  div.note { padding: 8pt; border: 2px solid; background-color: #F0AAAA; }
  div.note span.head { color: #BB0000; font-size: 14pt; font-weight: bold; }
  div.note li { padding: 3pt; }
  </style>
</head>
<body>

<h1>MORE</h1>
<h2>Links</h2>
<ul>
    <li><em>Trading Structure for Randomness in Wireless Opportunistic Routing</em> 
       [ <a href='http://www.sigcomm.org/ccr/drupal/?q=node/256'>PDF</a> ] <br>
    Szymon Chachulski, Michael Jennings, Sachin Katti and Dina Katabi <br>
    ACM SIGCOMM 2007. <br>
 <li>Source code: [ <a href='http://people.csail.mit.edu/szym/more/more-release-one.tgz'>TGZ</a> ]
</ul>

<h2>Features</h2>
<p>
As packaged here, MORE supports a limited set of features:
<ul>
<li> unicast and multicast (scripts support unicast only)
<li> single flow only
<li> static routing (i.e., there is no routing protocol)
<li> uniform synthetic traffic only (the batches are generated within Click)
</ul>

<p>
We are planning to address the missing features in the near future, depending
on the demand.

<div class='note'>
 <span class='head'>Important Notes</span> 
 <ul>
  <li> MORE sets the wireless interface (e.g.,<tt>ath0</tt>) in <em>monitor</em> mode.
  Such a "raw" interface is not suitable for Linux routing, therefore <u><tt>ath0</tt> cannot be used to control the testbed node remotely</u>.
  Although the madwifi-ng driver allows multiple VAPs (and it's also feasible to modify MORE to run in station mode), 
  it is highly recommended that a <em>separate</em> physical network interface is used to control the node
  so that experimental traffic does not interfere with control.

  <li> For effective network coding, MORE keeps the output buffering to minimum. However, this significantly increases the CPU overhead of
  user-kernel switching in this <u>user-level prototype</u>. This might substantially skew results, when comparing to in-kernel 
  implementation (e.g., native Linux routing), especially when using high wireless bit-rates. It is highly recommended that no bit-rates faster than 6Mbps
  are used for comparison.
 </ul>
</div>

<h1>Installing</h1>
<p>
As implemented here, MORE is a <em>userspace</em> program that communicates with the wireless
network interface via raw sockets to route its packets from the source to the 
destination.

<p>
MORE has been built on Click modular router and tested on Atheros 802.11 a/b/g
cards driven by the MadWifi driver on Linux 2.6. Running on other systems will 
require some porting. 

<p>
To truly test MORE, you will need at least 3 machines (source, destination and 
a forwarder) equipped with an Atheros wireless interface. 

To sum up, the steps required are:
<ol>
 <li> install <tt>madwifi-ng</tt> on testbed machines
 <li> build <em>userlevel</em> Click with MORE 
 <li> place <tt>click</tt> binary, <tt>config.py</tt> and <tt>startup.sh</tt> on 
   testbed machines (default location is <tt>~root/more</tt>)
 <li> place remaining scripts (or the whole <tt>conf</tt> directory)
   in your environment <tt>PATH</tt> on your experiment driving machine
 <li> create a <tt>nodes</tt> listing file and run experiments
</ol>

<h2>MadWifi</h2>
<p>
MadWifi is only needed to <em>run</em> Click with MORE, not build it. 

<p>
Follow the download instructions from
<a href='http://madwifi-project.org'>madwifi-project.org</a>.
MORE should work fine with both madwifi-old and madwifi-ng. However, this 
package has been specifically prepared for the release madwifi-0.9.3.3.
Follow the installation instructions from the driver package on your testbed 
machines.

<p>
If you previously had madwifi installed, you might have to remove
the old modules. That could require bringing the interface down and 
unloading the module <tt>ath_pci</tt>.

<h2>Click</h2>
<p>
Follow the download instructions from
<a href='http://read.cs.ucla.edu/click/download'>ucla.edu</a>.
This package was tested on Click releases 1.5.0 and 1.6.0.
<p>
To build Click with MORE, you need to place MORE source code as a subdirectory
to one of the enabled subdirectories in the <tt>/elements</tt> tree. For example you can 
place the source files under <tt>elements/local</tt>, but do not forget to <tt>--enable-local</tt> in 
the <tt>configure</tt>. Alternatively, place the source files in a subdirectory of 
<tt>/elements/wifi</tt>. 

<p>
MORE uses very few elements from click -- from userlevel, standard, 
ethernet, and wifi. Make sure that these element directories are enabled. 
MORE was tested in userlevel only.
You can disable linuxmodule, app, aqm, tcpudp, ip, icmp for faster build.
If you are building on a different machine than the testbed, you might
consider adding <tt>LDFLAGS=--static</tt>.

<p>
Build the userlevel click binary and place it on your testbed machines.

<h2>Router configuration</h2>
<p>
A core component of the package is the script <tt>config.py</tt>.
When executed on a testbed machine, it ensures that
the wireless interface is in the monitor ("raw") mode and generates a 
a Click configuration file including both MORE and a straw-man 
<em>single-path</em> router (SPP).

<h2>Routing</h2>
<p>
To compute static routing, you need to measure all-pair delivery probabilities 
in the selected transmitter configuration (channel, bitrate, tx power). Included 
in the package is a simple tool <tt>links.py</tt> that takes care of that. 

<p>
Like other scripts in this package, <tt>links.py</tt> uses <tt>nodes.py</tt> and a common format
of node list for management -- for each node in your testbed the list includes
the line:
<pre>
[IP] [MAC] [HOSTNAME]
</pre>
The scripts assume you can <tt>ssh root@IP</tt> without passwords (e.g., using <a href='http://www.linuxproblem.org/art_9.html'>keys</a>).
MAC is the hardware address of the wireless device and HOSTNAME is for convenience.
To find the MAC you can run (on the subject testbed machine):
<pre>
./config.py > /dev/null
</pre>
With default settings, it should read:
<pre>
using wifi0 / ath0 MAC 00:11:22:33:44:55
</pre>

<p>
NOTE: the assumed directory for <tt>click</tt>, <tt>config.py</tt> and <tt>startup.sh</tt> is <tt>/root/more</tt>. 
To change it, update <tt>RUNTIME_DIR</tt> in <tt>nodes.py</tt>.
The default name for the node list is <tt>./nodes</tt>.

<p>
The link measurement format used for computation is:
<pre>
[transmitter] [receiver] [bitrate] [delivery-prob]
</pre>
Where bitrate is the IEEE (2x) bit-rate (i.e, 5.5Mb/s is bitrate 11).

<h1>Example</h1>
<p>
To install Madwifi:
<pre>
make
make install  
</pre>
<p>
To configure and build click (assuming MORE is under elements/local):
<pre>
./configure --enable-wifi --enable-local
make
# copy userlevel/click to the testbed machines
</pre>
<p>
To setup runtime environment:
<pre>
# create the 'nodes' file, e.g.
10.0.0.1 00:AA:BB:CC:DD:EE host1
10.0.0.2 00:AA:BB:CC:DD:FF host2
# put click, config.py and startup.sh in your runtime dir on the testbed
</pre>
<p>
To setup all nodes on a common channel, e.g. 4, and  (and to quickly check if the 'nodes' file is correct):
<pre>
exec.py nodes 'iwconfig ath0 channel 4'
</pre>
<p>
To measure links at 1Mb/s:
<pre>
links.py -r 2 -o links2
# it takes a while!
# output in links2 could look like this:
host1 host2 2 0.5
host2 host1 2 1.0
</pre>
<p>
To run experiment:
<pre>
quickrun.py links2 host1 host2 spp
quickrun.py links2 host1 host2 more
# this writes the routing configuration to (spp|more).feed
# executes it
# and dumps the counters' readings to (spp|more).stats
</pre>

The resulting Python-parsable <tt>.stats</tt> file contains a dictionary storing,
for each hostname in <tt>nodes</tt>, a list of 5 strings:
outgoing DATA packets, 
outgoing ACK packets,
incoming packets, 
packets received (at sink),
average rate of packets received (at sink).

For example:
<pre>
{
'host1' : ['4200', '0', '64', '0', '0'] ,
'host2' : ['0', '64', '4188', '4160', '70.92'] ,
}
</pre>
We see host2 received 4160 packets at average rate of 70.92 per second.

<p>
<div class='note'>
<tt>NOTE:</tt> <em>Your mileage may vary.</em> The throughput gain of MORE <em>strongly depends</em> on the 
diversity in the network. For example, if both MORE and SPP transmit directly to the destination
(1-hop), then there is <em>no opportunistic gain</em> to be expected. 
Generally, we can expect better results, if the nodes in the network have high degrees of low quality links.
</div>

<h1>Change Log</h1>
<h2>2009-07-16</h2>
<ul>
 <li>Renamed <tt>_IO</tt> to avoid preprocessor macro clash on Debian.
</ul>

<h2>2009-04-08</h2>
<ul>
 <li>Added notes on setting the channel.
</ul>

<h2>2008-07-25</h2>
<ul>
 <li>Added "Important Notes".
</ul>

<h2>2007-11-27</h2>
<ul>
 <li>Released.
</ul>

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-2676160-1");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>

